<h1 class="Welcome">Exporting SNMP data with GANESHA</h1><br>
In
SNMP (Simple Network Management Protocol), data are organized as a tree
where all objects are addressed by their OID, which is the object's
path in this tree. For example,&nbsp;<span style="font-style: italic;">.iso</span> can be considered has a directory<br>
identified by the OID&nbsp;<span style="font-style: italic;">.1</span>, and the leaf&nbsp;<span style="font-style: italic;">.iso.org.dod.internet.mgmt.mib-2.system.sysDescr.0</span>
(which corresponds to system description) can be considered as a file
whose data is something&nbsp;"Linux node_name 2.6.9-22.ELsmp&nbsp;#1
SMP Mon Sep 19 18:32:14 EDT 2005 i686''.<br>
<br>
As a result, exporting such a tree through NFS makes it possible to have a filesystem similar to&nbsp;<span style="font-style: italic;">/proc</span>, where administrators can read statistics about a system or an equipment (switch, router, ...) simply using&nbsp;<span style="font-style: italic;">cat</span> command, and modify them easily, using <span style="font-style: italic;">vi</span> or <span style="font-style: italic;">echo</span>.<br>
<br>
This is what you can do using the SNMP FSAL. To use it, simply build GANESHA using the configure arg <br>
<div style="margin-left: 40px;">cd src<br>
./configure --with-fsal=SNMP<br>
make<br>
</div><br>
<br>
NB: Net-snmp library and includes must be installed on your system.<br>
<br>
<h2>SNMP relative options</h2><br>
<h3>The SNMP block</h3><h4>Parameters description</h4><br>
To configure GANESHA's SNMP access, you have to set some options in the configuration file: this in done in a SNMPconfiguration block.
<br>
<br>
In such a block, you can set the following values:<br>
<br>
<br>
<ul><li>snmp_version: this indicates the SNMP protocol version that GANESHA will use for communicating with SNMP agent. Expected values are</li><ul><li>&nbsp;&nbsp;&nbsp;&nbsp; 1, 2 or 3, default is 2</li></ul><li>snmp_server: this is the address of the SNMP master agent. A port number can also be specified by adding<span style="font-style: italic;"> :&lt;port&gt;</span> after the address. Default is localhost:161</li><li>nb_retries: number of retries for SNMP requests.</li><li>microsec_timeout: number of microseconds until first timeout, then an exponential backoff algorithm is used for next timeouts.</li><li>client_name: this is the client name that could be used internally by net-snmp for its traces.</li><li>snmp_getbulk_count: this indicates the number of responses wanted for each SNMP GETBULK request.</li></ul><br>
SNMP v1 and v2 specific parameters:<br>
<ul><li>community: this is the SNMP community used for authentication. Default is&nbsp;<span style="font-style: italic;">public</span>.<br>
</li></ul><br>
SNMP v3 specific parameters:<br>
<ul><li>auth_proto: the authentication protocol (MD5 or SHA)</li><li>enc_proto: the privacy protocol (DES or AES).</li><li>username: the security name (or user name).</li><li>auth_phrase: authentication passphrase (&gt;=8 char).</li><li>enc_phrase: authentication passphrase (&gt;=8 char)</li></ul><br>
<h3>A simple SNMP v2c example</h3><div style="margin-left: 40px;">SNMP<br>
{<br>
&nbsp;&nbsp;&nbsp; snmp_version = 2c;<br>
&nbsp;&nbsp;&nbsp; snmp_server = "snmp_master.my_net";<br>
&nbsp;&nbsp;&nbsp; community = "public";<br>
}<br>
</div><br>
<br>
<h3>A simple SNMP v3 example</h3><br>
<div style="margin-left: 40px;">SNMP<br>
{<br>
&nbsp;&nbsp;&nbsp; snmp_version = 3;<br>
&nbsp;&nbsp;&nbsp; snmp_server&nbsp; = "snmp_master.my_net";<br>
&nbsp;&nbsp;&nbsp; username&nbsp;&nbsp;&nbsp;&nbsp; = "snmpadm";<br>
&nbsp;&nbsp;&nbsp; auth_phrase&nbsp; = "p4ssw0rd!";<br>
&nbsp;&nbsp;&nbsp; enc_phrase&nbsp;&nbsp; = "p455w0rd?";<br>
}<br>
</div><br>
<br>
<br>
<h3>Export entries</h3><br>
For defining the path of an export entry, you must replace traditional<br>
SNMP dot separators `.' by slashes `/'. For example, you should<br>
set export path to `/iso/org' instead of `.iso.org'.<br>
<br>
Note that you can give slash separated numerical OIDs for exports. Thus,<br>
exporting `/1/3/6/1/2/1' is equivalent to `/iso/org/dod/internet/mgmt/mib-2'.<br>
<br>
<br>
<h3>Specific behaviors</h3><br>
Even if it is possible to export a SNMP tree as if it was a standard<br>
filesystem, SNMP however has some specificities that don't match<br>
POSIX or NFS semantics and features.<br>
<br>
<h4>Creating and removing objects</h4><br>
The goal of exporting SNMP with NFS is to make it possible<br>
for an administrator to browse statistics, to read them,<br>
and modify some agent's configuration variables.<br>
<br>
Thus, we don't have any interest in creating new entries<br>
(register some new values to SNMP agent)<br>
nor removing existing entries (unregister agent's objects).<br>
That would be very complex to operate and it could result<br>
in agent's problems or crashes...<br>
<br>
Another problem in SNMP is that object types are very<br>
different from NFS types: an object can be an integer,<br>
a string, a counter, a timetick, so it is difficult<br>
to know the type of data a NFS client is going to write<br>
to a newly created file...<br>
<br>
What's more, directories don't have a proper existence;<br>
they only exist if a child of them exist. As a result,<br>
creating or deleting an empty directory would<br>
have no sense in SNMP.<br>
<br>
For all those reasons,&nbsp;create and remove operations (create, mkdir, remove, rmdir) \textbf{are not supported}<br>
and return an&nbsp;EROFS error.<br>
<br>
<h4>Objects' attributes</h4>SNMP objects don't have the same metadata as NFS.<br>
They have no modification or access time,<br>
no owner, no inode number, etc... As a result,<br>
it has been necessary to emulate some<br>
of these attributes, to make the SNMP FSAL compatible<br>
with the NFS protocol.<br>
<br>
<br>
<h4>Setting attributes</h4><br>
Given that the only attributes that have an equivalence in SNMP<br>
are static (read-only), \textbf{no attributes are supported for setattr operations}.<br>
Thus, trying to change an attribute will result in a \texttt{EINVAL} error.<br>
<br>
<br>
<h4>String representation</h4><br>
SNMP objects divide in many types: integer, counter, gauge,<br>
string, opaque buffer, OID, timeticks, network address, etc.<br>
In order to make it easy to interpret, the data returned<br>
by a `read' operation is a string representation that depends<br>
on the object type.<br>
<br>
Indeed, even if integer, timeticks or IPv4 address are both<br>
32 bits values, the integer will be displayed as a numerical<br>
value, timeticks will be displayed as days/hours/minutes/seconds,<br>
and the network address will be displayed in the classical dot-separated<br>
notation.<br>
<br>
<br>
Some examples:<br>
<br>
<div style="margin-left: 40px;">$ cd /mnt/iso/org/dod/internet/mgmt/mib-2<br>
<br>
$ cat host/hrSystem/hrSystemUptime/0<br>
528224338 (61 days, 03:17:23.38)<br>
<br>
$ cat udp/udpInDatagrams/0<br>
820798<br>
<br>
$ cat udp/udpTable/udpEntry/udpLocalAddress/1/0/0/127/123<br>
127.0.0.1<br>
</div><br>
<br>
<br>
<h4>Modifying data</h4><br>
To modify a value, you just have to write a string representation to the associated file,<br>
using the way you want: a program, a script, or just the <span style="font-style: italic;">echo</span> command, ...<br>
<br>
For example:<br>
<div style="margin-left: 40px;">$ cd /mnt/iso/org/dod/internet/mgmt/mib-2<br>
$ echo "my_new_hostname" &gt; system/sysName/0<br>
</div><br>
<br>
But be careful: in SNMP, there are strong type constraints: you cannot<br>
write a string to an integer, etc. What's more, for a given object, the agent<br>
may also do extra checks (for example, if a configuration value<br>
is supposed to be a percentage, its SNMP type is unsigned integer,<br>
but the agent may return an error if you set a value greater than 100).<br>
<br>
In general, you have to rewrite data in the format of the value read in the file.<br>
The only exception is for timeticks: you must only write the value in 100th of seconds<br>
(not its translation to days, hours, minutes, seconds).<br>
<br>
An issue when developing the SNMP FSAL has been to translate&nbsp;<span style="font-style: italic;">invalid type</span><br>
SNMP errors to an appropriate NFS error code. Indeed, in NFS, there is<br>
no concept of invalid data content ! Returning NFSERR_INVAL or NFSERR_IO<br>
may result in a bad interpretation by the client, and it would be difficult<br>
for the client to distinguish the error from a real EIO or EINVAL error.<br>
So, it has been decided to convert such an error to NFSERR_DQUOT (that has no other sense with SNMP)<br>
so the user can know, with no ambiguity, that the value is not in the correct format,<br>
or is out of expected range.<br>
<br>

